<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Eclipse Project">
   <title>Resource Control</title>
   <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<h1>Resource Control</h1>

<blockquote> 
  <p><strong>Summary</strong>:<br>
    This document outlines problems with resource control in 2.1 and outlines 
    the requirements and possible solutions to these problems for the 3.0 release.</p>
  <p>Last Modified: May 6, 2003</p>
  </blockquote>
<hr>
<h2><a name="levelsofcontrol">Resource Control in Eclipse 2.X</a></h2>
<p>In Eclipse 2.x, several facilities give repository providers a certain level 
  of control over the resources in the workspace. Through these facilities, repository 
  providers are afforded the following:</p>
<ul>
  <li>Notification and control over resource moves and deletions via the move/delete 
    hook.</li>
  <li>Pre-modification notification for files via the validate save/edit mechanism.</li>
  <li>Notification and control over allowing linked resources via the team hook.</li>
  <li>Hiding of resources through the team-private resource property.</li>
</ul>
<h3>Problems with current facilities</h3>
<p>Although these facilities allow repository providers a high level of control 
  over what happens to resources in the projects shared with their repositories, 
  there are still several problems:</p>
<ol>
  <li>The current hooks are ad hoc in the sense that there are three separate 
    hooks and a resource property instead of one unified mechanism.</li>
  <li>Although repository providers have control over moves and deletes, they 
    have no control over copies (see bug 7) or additions.</li>
  <li>Deltas in the resources mapped to a repository provider can occur without 
    the provider being loaded. This can cause problems when a team provider relies 
    on deltas to mark resources as Team Private. (see bug 21128, 36483).</li>
  <li>Even when resources are hidden using the team-private property, changes 
    to these resource generate deltas and builds.</li>
  <li>Although the team-private property exists for the use of repository providers, 
    anyone can mark a resource team-private.</li>
  <li>A linked resource in a project may point to shared files in another project 
    (see bug 36685). In this scenario, operations on the project containing the 
    link do not provide team operations or move/delete or validate save/edit notifications.</li>
  <li>Non-providers may want control of resources. For example, binary projects 
    are associated with a repository provider just so PDE can have control of 
    the resources in a binary project.</li>
  <li>A provider may wish to prevent external editors launched from inside Eclipse 
    from modifying a file. This could be done by providing the external tool with 
    a copy of the file but, at the present time, there is no way to determine 
    when a copy should be used (see bug 36841).</li>
  <li>It would aid some workflows to support projects that only fetch remote contents 
    when they are edited (see bug 28215)</li>
</ol>
<h3><a name="levels"></a>Possible Levels of Control</h3>
<p>The amount of control that could be given to repository providers over resources 
  in Eclipse can be described using three levels.</p>
<blockquote>
  <p><strong>Level 1</strong>: Control of operations performed on resources. This 
    equates to what is provided in Eclipse 2.x by the team hooks with additional 
    notifications (i.e. copy and add). When a move, copy, delete or modification 
    is performed, the provider can control what happens in the file system or 
    veto the operation.</p>
  <p><strong>Level 2</strong>: Control of the mapping between resources in the 
    workbench and the underlying file system. This level of control would allow 
    the provider to be able to control what resources in the local file system 
    are mapped to resources in Eclipse. Thus, the provider could hide certain 
    resources (a.k.a. team-private). It could also potentially allow mappings 
    to other locations in the file system much like linked resources.</p>
  <p><strong>Level 3</strong>: Control of the mapping between resources and any 
    data source. This item would allow providers to map local resources in Eclipse 
    to remote resources (i.e. non-local resources).</p>
</blockquote>
<p>Level 1 is close to what Eclipse 2.X provides with the addition of copying 
  being managed in the same way as move/delete. Level 2 gives control of the resource 
  life-cycle to the provider. The provider would have control over all resource 
  methods (add, delete, move, copy, modify and refresh) and could thus ensure 
  that certain file system resources be excluded from Eclipse entirely. The final 
  level, level 3, also gives the provider control over where the contents of the 
  resource are located. This is actually a big step from the second level since 
  this would require an API change, at least in perception, in IResource since 
  fetching the content of resources could be long running.</p>
<p>Also, it is not necessary to say that only repository providers can control 
  resources. What is necessary is to ensure that there is only one controlling 
  entity. This could be a repository provider such as CVS or some other provider, 
  such as PDE for binary projects.</p>
<h3>Mapping of control</h3>
<p>Currently, the resource hooks are mapped to a repository provider through the 
  Team plugin. Since repository providers are project based, so are these hooks. 
  There are several reasons why repository providers are mapped at the project 
  level.</p>
<ul>
  <li>Given a resource, the associated repository provider can be easily and efficiently 
    determined.</li>
  <li>Originally, repository providers were project nature based. This mechanism 
    was used to associate which menu items were displayed in the Team menu for 
    a given project. Although the use of a natures have been replaced by a persistent 
    property on the project, menu determination is still project based.</li>
  <li>The mapping of projects to a repository provider and the sharing workspace 
    setup through project set import/export is straightforward.</li>
</ul>
<p>From a repository provider standpoint, there have been few disadvantages of 
  this organization that have been made known. One known problem involves linked 
  resources (see bug 36685) and others have appeared over time but have not been 
  recorded.</p>
<hr>
<h2><a name="filesystemprovider">Proposal: File System Provider</a></h2>
<p>Currently, the resource model is built directly on top of the local file system 
  as provided by java.io.File (and some direct calls through a DLL). However, 
  a more flexible approach is to separate the IResource facilities from the file 
  system using an abstraction barrier, as illustrated in Figure 1.</p>
<p><center>
    <p><img src="team3.0-filesystemprovider-picture.jpg" width="499" height="251" align="middle"></p>
    <p>Figure 1: File System Provider in context</p>
  </center></p>
<h3>&nbsp;</h3>
<p>In Figure 1, IResource still provides in-memory data structures and notifications 
  but delegates file system activity to a FileSystemProvider. The structure presented 
  in Figure 1 could potentially allow any of the <a href="#levels">levels of control</a> 
  described earlier. However, the initial intent will be to strive for level 2. 
  In 2.1 the Team Provider and the resource hooks where coupled whereas in the 
  above proposal they are independant. The role of the File System Provider is 
  to provide the physical resources the user works with and the role of the Team 
  provider is to share those resources with others. This separation allows non 
  Team Providers to control resources (zip/jar provider or a PDE binary project).</p>
<h3>Requirements</h3>
<p>Restatement of requirements from current implementation and known problems.</p>
<ul>
  <li>Minimize effect on IResource API</li>
  <li>Mapping of a File System Provider and Team Provider to any resource 
    <ul>
      <li>Team Provider decides if it can be mapped to a resource (contrary to 
        2.1 when the platform enforced a 1-1 rule). Part of its decision can be 
        based on whether the Team Provider can map its own custom File System 
        Provider to the resource.</li>
      <li>Team Provider doesn't have to register a File System Provider.</li>
    </ul>
  </li>
  <li>Hierarchical mappings for file system providers (child could be mapped to 
    a different provider than that of its parent)</li>
  <li>Subfolders mapped to alternate file system locations (a.k.a. linked resources)</li>
  <li>Independant from the Team Provider API</li>
  <li>Alternate implementions of FileSystemProvider 
    <ul>
      <li>hide files in file system from Eclipse (a.k.a. team-private)</li>
      <li>control/veto of file system operations (a.k.a move/delete hook, validateSave, 
        and others)</li>
      <li>provider is loaded aggresively and won't miss any resource delegation</li>
    </ul>
  </li>
  <li>Must be scalable (e.g. efficient lookup of file system provider given a 
    resource)</li>
  <li>Should be made as easy as possible to implement small changes in behavior 
    for the default FileSystemProvider</li>
  <li>Validate edit must still be supported but it may be best to leave out of 
    the File System Provider API</li>
  <li>Must be able to recreate the workspace (refactor the IProjectSets interface)</li>
  <li>Object contribution should be enabled for a File System Providers and Team 
    Providers</li>
</ul>
